About Using Personal Access Tokens in APIs

Before this release, you had to make a web request to an external IdP for a token to include in API scripts. Now you can use PAT identifiers as strings in API authentication headers, reducing the amount of code required. Reference PAT identifiers stored in a file or key vault, or define global variables.

Watch to see how to manage PATs (3:25).

See:

Best Practices.
Authentication Header Updates.
API Call Comparison.

For information about OneStream APIs, see:

The API Overview Guide.
The REST API Implementation Guide.

Best Practices

While you can paste copied PAT identifiers in API scripts, we suggest you more securely reference them systematically to retrieve them from an external storage source such as file repository or key vault.

To avoid authentication errors, work as needed with an administrator to ensure that:

Your user account is active in OneStream. Verify account status by clicking System > Security > Users > <user> and ensuring Is Enabled is True.
You have not exceeded your log on inactivity threshold. See "Managing Users" in the Design and Reference Guide.
You have group-based access to the AccessAsNonInteractiveUser security role. See Required System Security Roles.
Your PAT is not legacy, IdP-based. Use only PATs generated in the Identity & Access Management Portal.
You use the complete PAT identifier string.
A PAT did not expire and was not revoked.

Authentication Header Updates

In 7.0 legacy API calls, update authentication strings as the following to replace clientID, usernames, and passwords with a unique PAT identifier string.

For example, insert the following to reference a PAT identifier stored in an Azure key vault:

$token = Get-AzKeyVaultSecret -VaultName '<name>' -Name 'PATAdmin' -AsPlainText

While not recommended for security reasons, you could also replace the code below:

Get Authentication Token Dim authToken As String = GetClientCredentials AuthToken0S(si, methodType, authorizationURL, clientID, ClientSecret, grantType, scope) ErrorHandler.LogMessage(si, authToken)

with a copied PAT identifier that you paste into the string:

Get Authentication Token Dim authToken As String = "<PAT identifier>" ErrorHandler.LogMessage si,authToken)

Then save and run scripts against APIs.

API Call Comparison

To illustrate release-specific differences in portions of API call scripts, this section compares the same ExecuteSequence API call.

Legacy

The first 20 lines of code below request a token from an external IdP. The remaining lines use the returned token to authenticate and run a business rule to export data.

Current

Referencing a PAT generated in the Identity & Access Management Portal significantly reduces the code required. The following code references a PAT identifier from a key vault: